<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>cocoOS: docFundamentals.h File Reference</title>

<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>


</head>
<body>
<div id="top"><!-- do not remove this div! -->


<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  
  
  <td style="padding-left: 0.5em;">
   <div id="projectname">cocoOS
   &#160;<span id="projectnumber">3.0.0</span>
   </div>
   
  </td>
  
  
  
 </tr>
 </tbody>
</table>
</div>

<!-- Generated by Doxygen 1.7.6 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li class="current"><a href="files.html"><span>Files</span></a></li>
    </ul>
  </div>
  <div id="navrow2" class="tabs2">
    <ul class="tablist">
      <li><a href="files.html"><span>File&#160;List</span></a></li>
      <li><a href="globals.html"><span>Globals</span></a></li>
    </ul>
  </div>
</div>
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
  initNavTree('doc_fundamentals_8h.html','');
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">docFundamentals.h File Reference</div>  </div>
</div>
<div class="contents">
<hr/><a name="details" id="details"></a><h2>Detailed Description</h2>
<div class="textblock"><p><b> Introduction </b> <br/>
 cocoOS is a free, open source, cooperative task scheduler, based on coroutines. <br/>
</p>
<p>Task procedures scheduled by cooperative kernels are so called RTC's, run to completion tasks. They execute from the first line of the procedure to the last line. The use of coroutines enables us to implement task procedures that does not have to execute all the way down to the last line of code. Instead execution can end in the middle e.g waiting for a semaphore to be released. When execution is resumed, it continues at that line. <br/>
 <br/>
</p>
<p>With coroutines, this can be done without having to save the complete task context when switching to another task. Also, task procedures can be outlined in the same style as when using a traditional preemptive RTOS.</p>
<p>cocoOS is extremely portable to any target which makes it a perfect choice during early phases of the development when which OS to use is still an open issue.</p>
<p><b>Getting Started </b><br/>
</p>
<p><b>Configuration </b><br/>
 To setup cocoOS you have to define 4 constants in <a class="el" href="os__defines_8h.html">os_defines.h</a>. These are: <br/>
</p>
<ul>
<li>N_TASKS: maximum number of tasks</li>
<li>N_QUEUES: maxmimum number of message queues</li>
<li>N_SEMAPHORES: maximum number of semaphores</li>
<li>N_EVENTS: maximum numer of events</li>
</ul>
<p>Allowed range for these constants is 0-254. These constants sets the maximum value for the number of used ojects of the specified types. It is allowed to use fewer but not more number of objects. To save RAM it is recommended to keep these values as low as possible. <br/>
</p>
<p><b>System setup - application main function </b> <br/>
 As usual you have to setup your system, ports, clocks etc in the beginning of your main function. It is also in the main function you create all tasks, semaphores and events. As final steps in the setup you call <a class="el" href="os__appl_a_p_i_8h.html#a6cc2e63d83267ff5059bf0a76b302a09">os_init()</a> to setup the kernel and finally you start the clock and places a call to <a class="el" href="os__appl_a_p_i_8h.html#a19c7111cf2121a69331d99dabe3e9df0">os_start()</a>. <br/>
 <br/>
 </p>
<div class="fragment"><pre class="fragment"><span class="keywordtype">int</span> main(<span class="keywordtype">void</span>) {
  <span class="comment">/* Setup ports, clock... */</span>
  system_init();
  
  <a class="code" href="os__appl_a_p_i_8h.html#a6cc2e63d83267ff5059bf0a76b302a09">os_init</a>();
  
  <span class="comment">/* Create kernel objects */</span>
  <a class="code" href="os__appl_a_p_i_8h.html#adb53dc7146d0e27f8ac2675f62dd6124">task_create</a>( myTaskProc, 1, NULL, 0, 0 );
  mySem = <a class="code" href="os__appl_a_p_i_8h.html#aaecd95706696b8ff18d5ef74d139d750">sem_bin_create</a>( 1 );
  
  
  clock_start();
  
  enable_interrupts();
  
  <a class="code" href="os__appl_a_p_i_8h.html#a19c7111cf2121a69331d99dabe3e9df0">os_start</a>();
  
  <span class="comment">/* Will never end up here */</span>
  <span class="keywordflow">return</span> 0;
}
</pre></div><p>This is the preferred order of initialization. It is crucial that the clock is not started before the tasks are created and the kernel is initialized.</p>
<p><b>Time </b><br/>
 cocoOS keeps track of time by counting ticks and you must feed the counting with a call to <a class="el" href="os__appl_a_p_i_8h.html#a1d7bc0554f6b515785211dd2c3f2d3d9">os_tick()</a> periodically from the clock tick ISR.</p>
<p>A system of one main clock and several sub clocks is used in cocoOS. The main clock is typically realized using one of the hardware timers within your target microcontroller which calls the <a class="el" href="os__appl_a_p_i_8h.html#a1d7bc0554f6b515785211dd2c3f2d3d9">os_tick()</a> function that decrements the timers used for <a class="el" href="os__appl_a_p_i_8h.html#ad8232a672a6d4f3a4532bea410a0b1ef">task_wait()</a>, <a class="el" href="os__appl_a_p_i_8h.html#abaae70bdc9e52397b8cb61698d850cda">msg_post_in()</a> and <a class="el" href="os__appl_a_p_i_8h.html#a1d4ff9caf0714728a46973fe7ef76868">msg_post_every()</a>. If your application does not need more than a single time base, the main clock fed by the <a class="el" href="os__appl_a_p_i_8h.html#a1d7bc0554f6b515785211dd2c3f2d3d9">os_tick()</a> call is all you need. <br/>
</p>
<p>In case your application has to react to events in another time resolution than what is provided by the main clock, you can use the sub clocks. The sub clocks are typically not associated with a hardware timer, but is instead "ticked" by calling os_sub_tick(id) from within your application code.</p>
<p>Sub clocks can also be advanced with a step greater than one using os_sub_nTick(id, nTicks). There is one task function associated with the sub clocks: <a class="el" href="os__appl_a_p_i_8h.html#aade8755cf226e97b98eff894310f4257">task_wait_id(id,ticks)</a>. id is a value in the range 1-255 assigned by the application, and ticks is the number of ticks to wait. An example of the use of sub clocks could be a task that should be run after 64 bytes has been received on the UART. The task starts the wait by calling <a class="el" href="os__appl_a_p_i_8h.html#aade8755cf226e97b98eff894310f4257">task_wait_id( 1, 64 )</a>. And in the UART rx ISR os_sub_tick(1) is called for each received character.</p>
<p><b>Tasks </b><br/>
 An application is built up by a number of tasks. Each task is a associated with a (preferably short) procedure with a well defined purpose. The execution of the tasks, is managed by the os kernel, by letting the highest priority task among all execution ready tasks to execute. All tasks have to make at least one blocking call to a sheduling kernel function. This gives lower priority tasks a chance to execute.</p>
<p>The task procedure must enclose its code with the <a class="el" href="os__appl_a_p_i_8h.html#ac19d6a48c1cb673360ae220aaf2a9d53">task_open()</a> and <a class="el" href="os__appl_a_p_i_8h.html#a7912af19af4a033fd9caf27879614945">task_close()</a> macros, as shown below.</p>
<div class="fragment"><pre class="fragment"><span class="keyword">static</span> <span class="keywordtype">void</span> task(<span class="keywordtype">void</span>) {
  <a class="code" href="os__appl_a_p_i_8h.html#ac19d6a48c1cb673360ae220aaf2a9d53">task_open</a>();
  ...
  ...
  <a class="code" href="os__appl_a_p_i_8h.html#a7912af19af4a033fd9caf27879614945">task_close</a>();
}
</pre></div><p>Such a task will be executed once only. If a task is intended to be executed "for ever", an endless loop must be implemented.</p>
<div class="fragment"><pre class="fragment"><span class="keyword">static</span> <span class="keywordtype">void</span> hello_task(<span class="keywordtype">void</span>) {
  <a class="code" href="os__appl_a_p_i_8h.html#ac19d6a48c1cb673360ae220aaf2a9d53">task_open</a>();
    <span class="keywordflow">for</span>(;;) {
      uart_send_string(<span class="stringliteral">&quot;Hello World!&quot;</span>);
      <a class="code" href="os__appl_a_p_i_8h.html#ad8232a672a6d4f3a4532bea410a0b1ef">task_wait</a>( 20 );
    }
  <a class="code" href="os__appl_a_p_i_8h.html#a7912af19af4a033fd9caf27879614945">task_close</a>();
}



<span class="keywordtype">int</span> main(<span class="keywordtype">void</span>) {
  <span class="comment">/* Setup ports, clock... */</span>
  system_init();
  
  <span class="comment">/* Create kernel objects */</span>
  <a class="code" href="os__appl_a_p_i_8h.html#adb53dc7146d0e27f8ac2675f62dd6124">task_create</a>( hello_task, 1, NULL, 0, 0 );
  
  <a class="code" href="os__appl_a_p_i_8h.html#a6cc2e63d83267ff5059bf0a76b302a09">os_init</a>();
  clock_start();
  <a class="code" href="os__appl_a_p_i_8h.html#a19c7111cf2121a69331d99dabe3e9df0">os_start</a>();
  
  <span class="comment">/* Will never end up here */</span>
  <span class="keywordflow">return</span> 0;
}
</pre></div><p><b>Scheduling</b><br/>
 When a task has finished it gives the CPU control to another task by calling one of the scheduling macros:</p>
<ul>
<li><a class="el" href="os__appl_a_p_i_8h.html#ad8232a672a6d4f3a4532bea410a0b1ef">task_wait()</a></li>
<li><a class="el" href="os__appl_a_p_i_8h.html#a576b2326d068ab852846ee612c7b954c">event_wait()</a></li>
<li><a class="el" href="os__appl_a_p_i_8h.html#adf6bffac3935c670ced14cf963fb0427">event_wait_timeout()</a></li>
<li><a class="el" href="os__appl_a_p_i_8h.html#a148bf0f2ab640ccf1cf29229d61defb6">event_wait_multiple()</a></li>
<li><a class="el" href="os__appl_a_p_i_8h.html#a194e9ed0f676ffc46a782754b58a0475">event_signal()</a></li>
<li><a class="el" href="os__appl_a_p_i_8h.html#ab14d890b777d3b2a9e4c83a3ec15dd31">sem_wait()</a></li>
<li><a class="el" href="os__appl_a_p_i_8h.html#aa5011c236fb03784283e6476e9ae5adb">sem_signal()</a></li>
<li><a class="el" href="os__appl_a_p_i_8h.html#ae66288422355db64c18c53676e53eddb">msg_q_get()</a></li>
<li><a class="el" href="os__appl_a_p_i_8h.html#adc67691f29549315143cc60ff43e2306">msg_q_give()</a></li>
<li><a class="el" href="os__appl_a_p_i_8h.html#a017f7852a4fe5b619c58a9adf3d57bd7">msg_post()</a></li>
<li><a class="el" href="os__appl_a_p_i_8h.html#abaae70bdc9e52397b8cb61698d850cda">msg_post_in()</a></li>
<li><a class="el" href="os__appl_a_p_i_8h.html#a1d4ff9caf0714728a46973fe7ef76868">msg_post_every()</a></li>
<li><a class="el" href="os__appl_a_p_i_8h.html#ac09ba62464c1027ee133b7a6878bfa83">msg_receive()</a></li>
</ul>
<p>Normally the scheduler will give the cpu to the highest priority task ready for execution. It is possible to choose a round robin scheduling algorithm by putting the following line in <a class="el" href="os__defines_8h.html">os_defines.h</a>:<br/>
 #define ROUND_ROBIN</p>
<p>This will make the scheduler to scan the list of tasks and run the next found task in the ready state. </p>
</div></div>
</div>
  <div id="nav-path" class="navpath">
    <ul>
      <li class="navelem"><a class="el" href="doc_fundamentals_8h.html">docFundamentals.h</a>      </li>

    <li class="footer">Generated on Thu Dec 22 2011 21:14:42 for cocoOS by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.6 </li>
   </ul>
 </div>


</body>
</html>
